---
title: Getting Started
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

:::info

The following content is for **[DocSearch v3][2]**.
If you are using **[DocSearch v2][3]**, see the **[legacy][4]** documentation.

If you are looking for **DocSearch v4**, see the documentation **[here][17]**.

:::

## Introduction

DocSearch v3 is built on top of the latest version of [Algolia Autocomplete][1], which provides better accessibility, increased responsiveness, themability, a better built-in design, and customizability under low-network conditions.

This version has been rewritten in React, and now exposes React components. The vanilla JavaScript version is based on the React version with an alias to Preact.

### Stable version

With the recent release of the stable version of [Algolia Autocomplete][1], and the huge adoption of DocSearch v3, we will start working on a stable release!

Thanks to all the Alpha testers, and to [all the integrations][5] who already support it!

## Installation

DocSearch packages are available on the [npm][10] registry.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```bash
yarn add @docsearch/js@3
# or
npm install @docsearch/js@3
```

### Without package manager

If you don't want to use a package manager, you can add the CSS to the `<head>` of your website:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
```

</TabItem>
<TabItem value="react">

```bash
yarn add @docsearch/react@3
# or
npm install @docsearch/react@3
```

### Without package manager

If you don't want to use a package manager, you can add the CSS to the `<head>` of your website:

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
```

And the JavaScript at the end of your `<body>`:

```html
<script src="https://cdn.jsdelivr.net/npm/@docsearch/react@3"></script>
```

</TabItem>

</Tabs>

### Improve first query speed

You can hint the browser to improve the speed of the first query by adding a `preconnect`, see [#preconnect](#preconnect)

## Implementation

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

To get started, you need a [`container`][11] for your DocSearch component to go in. If you don’t have one already, you can insert one into your markup:

```html
<div id="docsearch"></div>
```

Then, insert DocSearch into it by calling the [`docsearch`][12] function and providing the container. It can be a [CSS selector][6] or an [Element][7].

Make sure to provide a [`container`][11] (for example, a `div`), not an `input`. DocSearch generates a fully accessible search box for you.

```js app.js
import docsearch from '@docsearch/js';

import '@docsearch/css';

docsearch({
  container: '#docsearch',
  appId: 'YOUR_APP_ID',
  indexName: 'YOUR_INDEX_NAME',
  apiKey: 'YOUR_SEARCH_API_KEY',
});
```

</TabItem>

<TabItem value="react">

DocSearch generates a fully accessible search box for you.

```jsx App.js
import { DocSearch } from '@docsearch/react';

import '@docsearch/css';

function App() {
  return (
    <DocSearch
      appId="YOUR_APP_ID"
      indexName="YOUR_INDEX_NAME"
      apiKey="YOUR_SEARCH_API_KEY"
    />
  );
}

export default App;
```

</TabItem>

</Tabs>

### Testing

If you're eager to test DocSearch v3 and can't wait to receive your credentials, you can use ours!

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  appId: 'PMZUYBQDAK',
  apiKey: '24b09689d5b4223813d9b8e48563c8f6',
  indexName: 'docsearch',
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  appId="PMZUYBQDAK"
  apiKey="24b09689d5b4223813d9b8e48563c8f6"
  indexName="docsearch"
/>
```

</TabItem>

</Tabs>

### Filtering your search

If your website supports [DocSearch meta tags][13] or if you've added [custom variables to your config][14], you'll be able to use the [`facetFilters`][16] option to scope your search results to a [`facet`][15]

This is useful to limit the scope of the search to one language or one version.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  searchParameters={{
    facetFilters: ['language:en', 'version:1.0.0'],
  }}
/>
```

</TabItem>

</Tabs>

### Sending events

You can send search events to your DocSearch index by passing in the `insights` parameter when creating your DocSearch instance.

<Tabs
  groupId="language"
  defaultValue="js"
  values={[
    { label: 'JavaScript', value: 'js', },
    { label: 'React', value: 'react', }
  ]
}>
<TabItem value="js">

```js
docsearch({
  searchParameters: {
    facetFilters: ['language:en', 'version:1.0.0'],
  },
  insights: true,
});
```

</TabItem>

<TabItem value="react">

```jsx
<DocSearch
  searchParameters={{
    facetFilters: ['language:en', 'version:1.0.0'],
  }}
  insights
/>
```

</TabItem>

</Tabs>

## Performance optimization

### Preconnect

By adding this snippet to the `head` of your website, you can hint the browser that the website will load data from Algolia, and allows it to preconnect to the DocSearch cluster. It makes the first query faster, especially on mobile.

```html
<link rel="preconnect" href="https://YOUR_APP_ID-dsn.algolia.net" crossorigin />
```

[1]: https://www.algolia.com/doc/ui-libraries/autocomplete/introduction/what-is-autocomplete/
[2]: https://github.com/algolia/docsearch/
[3]: https://github.com/algolia/docsearch/tree/master
[4]: /docs/legacy/dropdown
[5]: /docs/integrations
[6]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[7]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
[8]: https://codesandbox.io/s/docsearch-js-v3-playground-z9oxj
[9]: https://codesandbox.io/s/docsearch-react-v3-playground-619yg
[10]: https://www.npmjs.com/
[11]: /docs/api#container
[12]: /docs/api
[13]: /docs/required-configuration#introduce-global-information-as-meta-tags
[14]: /docs/record-extractor#indexing-content-for-faceting
[16]: https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/#facetfilters
[15]: https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/
[17]: /docs/docsearch
